Electron 应用自动更新配置
概述
Electron 应用的自动更新（Auto Update）允许应用在发布新版本后自动检测、下载并安装更新。electron-builder 内置了自动更新支持，通过 electron-updater 库配合 GitHub Releases 作为发布源，可以实现静默更新。
自动更新流程
应用启动 → checkForUpdatesAndNotify()
↓
检测 GitHub Releases 最新版本
↓
比较版本号 (semver)
↓
发现新版本 → 后台静默下载
↓
下载完成 → 下次启动时自动安装更新
text
配置步骤
Step 1：安装 electron-updater
npm install electron-updater
# 或
pnpm add electron-updater
bash
Step 2：配置 publish（发布源）
// electron-builder.config.js
module.exports = {
appId: 'com.example.myapp',
productName: 'MyApp',
// ...
publish: {
provider: 'github', // 使用 GitHub Releases 作为发布源
owner: 'your-username',
repo: 'your-repo'
},
// 也支持其他发布源
// publish: {
// provider: 'generic',
// url: 'https://your-update-server.com/updates/'
// }
}
javascript
发布源选项对比
| Provider | 说明 | 配置要求 |
|---|---|---|
github | GitHub Releases（默认推荐） | 配置 GH_TOKEN 环境变量 |
generic | 自定义 HTTP 服务器 | 提供更新文件 URL |
s3 | Amazon S3 存储 | 配置 AWS 凭证 |
spaces | DigitalOcean Spaces | 配置 DO 凭证 |
Step 3：主进程集成 autoUpdater
// main/index.ts（主进程入口）
import { app, BrowserWindow } from 'electron'
import { autoUpdater } from 'electron-updater'
// 基础用法：自动检查并通知
function setupAutoUpdater() {
// 自动下载并通知用户
autoUpdater.checkForUpdatesAndNotify()
}
// 高级用法：监听更新事件
function setupAutoUpdaterAdvanced(mainWindow: BrowserWindow) {
// 配置
autoUpdater.autoDownload = true // 自动下载
autoUpdater.autoInstallOnAppQuit = true // 退出时自动安装
// 检查更新失败
autoUpdater.on('error', (error) => {
console.error('Auto update error:', error)
})
// 检查更新中
autoUpdater.on('checking-for-update', () => {
console.log('Checking for update...')
})
// 发现新版本
autoUpdater.on('update-available', (info) => {
console.log('Update available:', info.version)
// 可通知渲染进程显示更新提示
mainWindow.webContents.send('update-available', info)
})
// 已是最新版本
autoUpdater.on('update-not-available', (info) => {
console.log('Current version is up-to-date:', info.version)
})
// 下载进度
autoUpdater.on('download-progress', (progressInfo) => {
console.log(`Download progress: ${progressInfo.percent.toFixed(1)}%`)
mainWindow.webContents.send('download-progress', progressInfo)
})
// 下载完成
autoUpdater.on('update-downloaded', (info) => {
console.log('Update downloaded:', info.version)
// 通知渲染进程
mainWindow.webContents.send('update-downloaded', info)
})
autoUpdater.checkForUpdates()
}
app.whenReady().then(() => {
const mainWindow = new BrowserWindow({ /* ... */ })
// 在生产环境中启用自动更新
if (app.isPackaged) {
setupAutoUpdaterAdvanced(mainWindow)
}
})
typescript
Step 4：渲染进程处理更新通知
// renderer 端监听更新事件
// preload.ts
import { contextBridge, ipcRenderer } from 'electron'
contextBridge.exposeInMainWorld('electronAPI', {
onUpdateAvailable: (callback: (info: any) => void) =>
ipcRenderer.on('update-available', (_, info) => callback(info)),
onDownloadProgress: (callback: (progress: any) => void) =>
ipcRenderer.on('download-progress', (_, progress) => callback(progress)),
onUpdateDownloaded: (callback: (info: any) => void) =>
ipcRenderer.on('update-downloaded', (_, info) => callback(info)),
quitAndInstall: () => ipcRenderer.send('quit-and-install'),
})
// main 进程响应安装请求
ipcMain.on('quit-and-install', () => {
autoUpdater.quitAndInstall()
})
typescript
GitHub Actions 自动发布
# .github/workflows/release.yml
name: Release
on:
push:
tags:
- 'v*'
jobs:
release:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [macos-latest, ubuntu-latest, windows-latest]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: pnpm install --frozen-lockfile
- run: pnpm build
# GH_TOKEN 是必须的环境变量，变量名不能更改
- name: Publish Release
run: pnpm electron-builder --publish always
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
yaml
环境变量说明
| 变量名 | 说明 | 是否必须 |
|---|---|---|
GH_TOKEN | GitHub Personal Access Token | 是（发布时） |
GITHUB_TOKEN | GitHub Actions 自动提供的 token | Actions 中自动注入 |
注意：
GH_TOKEN变量名是固定的，不能随意更改。electron-builder 依赖此变量名来识别认证信息。
版本号管理
// package.json
{
"version": "1.0.0"
}
json
- 每次发布前必须更新
version字段 electron-updater使用 semver 比较版本号- 发布流程：修改 version → 打 git tag → 推送 tag → Actions 自动构建发布
自动更新工作模式
| 模式 | 说明 |
|---|---|
| 静默更新 | 后台下载，下次启动安装（默认） |
| 通知更新 | 弹窗提示用户下载安装 |
| 强制更新 | 阻止使用旧版本 |
实践要点
electron-updater仅在生产环境（app.isPackaged）中生效，开发环境不触发- GitHub 作为发布源时，
GH_TOKEN变量名不可更改 - 更新文件需要上传到 GitHub Releases，包含
latest-mac.yml、latest-linux.yml等元数据文件 autoUpdater.checkForUpdatesAndNotify()是最简用法，一行代码实现检测+通知- 自定义更新服务器（generic provider）需提供符合 electron-updater 格式的更新清单文件
↑